Docs As Part Of The Developer Experience For MSAL

I am a big believer in good documentation being an essential part of the product. Good docs are hard to come by for several reasons, not the least being the fact that writing good docs is hard.

It takes time, it requires product expertise, and, when it comes to technical products, requires the involvement of the engineering team in the process. Engineering teams often have reasons not to work on documentation - the backlog is too large, there are higher priority tasks, writing documentation is tedious, or there is no clear path to who the documentation is written for to begin with, so naturally all writing and content reviews are delegated to someone else.

As a corollary to the above, I strongly believe that good docs for technical products require the engineering team to be a core contributor to those because the engineering team has unmatched expertise in the ins and outs of the tool, library, or the API being built.

Notice that I didn’t mention that engineers should be the ones writing all the docs - they should be a core contributor. There is still a lot of value in product managers and content developers helping drive the end-to-end story, but without the engineering value-add it can never be truly great.

Good documentation is the foundation of a good developer experience. Miguel de Icaza said it best:

Long story longer, that’s actually part of the reason why I am excited that our team (engineering, content, and product management) just shipped the documentation for the Microsoft Authentication Library for .NET on learn.microsoft.com.

The bulk of the content we moved from the GitHub Wiki - there is a way to treat the Wiki as a Git repo however that would not be possible to integrate properly with the rest of the documentation pipeline, so the train absolutely had to leave the station. GitHub Wikis are very easy to edit but also are somewhat cumbersome to manage properly once the content set grows larger and larger - and we kind of outgrew the capabilities of the Wiki.

To add to that, the move to Microsoft Learn allowed us to also auto-generate all the reference documentation for the SDK, the docs being an immediate reflection of the public API.

The documentation is now:

1. In one place. Easy for developers to find it because the API docs and the conceptual tutorials are covered together in one table of contents. No need to jump between sites and wikis.
2. Version controlled. Just like software, every change is captured in the commit history.
3. Shipped like software. It’s all on GitHub. Changes are commited through git and are reviewed just like code is reviewed - through pull requests and automated tests. We do validation with the help of Open Publishing (an internal Microsoft documentation pipeline) and Lychee, as some examples.
4. Extremely easy to edit. Folks of all skill levels can now go to GitHub, or even start with a documentation page, and contribute to it. It’s also Markdown - not any other fancy format.
5. Localizable. By using the common publishing pipeline we are now able to easily create translated versions of all tutorials and reference docs.

The docs are collaboratively written by the engineering team, the PM team, and our content developers. At its core, it’s documentation written by developers, for developers.

We’d love to hear your feedback - there is a lot of work ahead (when is documentation ever done) but we’re looking at optimizing and improving the content so that those that rely on MSAL for authentication can get to the desired state as soon as humanly possible. Leave us a note!